<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE dita PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">
<dita>
  <topic id="topic_fstrm">
    <title>pageinspect</title>
    <body>
      <p>The <codeph>pageinspect</codeph> module provides functions for low level
         inspection of the contents of database pages. <codeph>pageinspect</codeph>
         is available only to Greenplum Database superusers.</p>
      <p>The Greenplum Database <codeph>pageinspect</codeph> module is based on the
        PostgreSQL <codeph>pageinspect</codeph> module. The Greenplum version of the
        module differs as described in the <xref href="#topic_gp"/> topic.</p>
    </body>
    <topic id="topic_reg">
      <title>Installing and Registering the Module</title>
      <body>
        <p>The <codeph>pageinspect</codeph> module is installed when you install
          Greenplum Database. Before you can use any of the functions defined in the
          module, you must register the <codeph>pageinspect</codeph> extension in
          each database in which you want to use the functions:</p>
        <codeblock>CREATE EXTENSION pageinspect;</codeblock>
        <p>Refer to <xref href="../../install_guide/install_modules.html"
            format="html" scope="external">Installing Additional Supplied Modules</xref>
          for more information.</p>
      </body>
    </topic>
    <topic id="topic_upgrade">
      <title>Upgrading the Module</title>
      <body>
        <p>If you are currently using <codeph>pageinspect</codeph> in your Greenplum
          installation and you want to access newly-released module functionality, you
          must update the <codeph>pageinspect</codeph> extension in every database in which
          it is currently registered:</p>
        <codeblock>ALTER EXTENSION pageinspect UPDATE;</codeblock>
      </body>
    </topic>
    <topic id="topic_info">
      <title>Module Documentation</title>
      <body>
        <p>See <codeph><xref href="https://www.postgresql.org/docs/9.4/pageinspect.html"
            scope="external" format="html">pageinspect</xref></codeph> in the PostgreSQL
          documentation for detailed information about the majority of functions in this
          module.</p>
        <p>The next topic includes documentation for Greenplum-added
          <codeph>pageinspect</codeph> functions.</p>
      </body>
    </topic>
    <topic id="topic_gp">
      <title>Greenplum Database Considerations</title>
      <body>
        <p>When using this module with Greenplum Database, consider the following:</p>
        <ul>
          <li>The Greenplum Database version of the <codeph>pageinspect</codeph> does not
            allow inspection of pages belonging to append-optimized or external relations.</li>
          <li>For <codeph>pageinspect</codeph> functions that read data from a database, the
            function reads data only from the segment instance where the function is run. For
            example, the <codeph>get_raw_page()</codeph> function returns a <codeph>block number out
            of range</codeph> error when you try to read data from a user-defined table on the
            Greenplum Database master because there is no data in the table on the master segment. The
            function will read data from a system catalog table on the master segment.</li>
        </ul>
       <section id="gp_funcs">
        <title>Greenplum-Added Functions</title>
        <p>In addition to the functions specified in the PostgreSQL documentation, 
          Greenplum Database provides these additional <codeph>pageinspect</codeph>
          functions for inspecting bitmap index pages:</p>
        <table id="gpfuncs">
        <tgroup cols="2">
          <colspec colname="col1" colnum="1" colwidth="177*"/>
          <colspec colname="col2" colnum="2" colwidth="186*"/>
          <thead>
            <row>
              <entry colname="col1">Function Name</entry>
              <entry colname="col2">Description</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry colname="col1">bm_metap(relname text) returns record</entry>
              <entry colname="col2">Returns information about a bitmap index's meta page.</entry>
            </row>
            <row>
              <entry colname="col1">bm_bitmap_page_header(relname text, blkno int) returns record</entry>
              <entry colname="col2">Returns the header information for a bitmap page; this
                corresponds to the opaque section from the page header.</entry>
            </row>
            <row>
              <entry colname="col1">bm_lov_page_items(relname text, blkno int) returns setof record</entry>
              <entry colname="col2">Returns the list of value (LOV) items present in a bitmap
                LOV page.</entry>
            </row>
            <row>
              <entry colname="col1">bm_bitmap_page_items(relname text, blkno int) returns setof record</entry>
              <entry colname="col2">Returns the content words and their compression statuses
                for a bitmap page.</entry>
            </row>
            <row>
              <entry colname="col1">bm_bitmap_page_items(page bytea) returns setof record</entry>
              <entry colname="col2">Returns the content words and their compression statuses
                for a page image obtained by <codeph>get_raw_page()</codeph>.</entry>
            </row>
          </tbody>
        </tgroup>
        </table>
       </section>
       <section id="topic_examples">
       <title>Examples</title>
        <p>Greenplum-added <codeph>pageinspect</codeph> function usage examples follow.</p>
        <p>Obtain information about the meta page of the bitmap index named <codeph>i1</codeph>:</p>
        <codeblock>testdb=# SELECT * FROM bm_metap('i1');
   magic    | version | auxrelid | auxindexrelid | lovlastblknum
------------+---------+----------+---------------+---------------
 1112101965 |       2 |   169980 |        169982 |             1
(1 row)</codeblock>
        <p>Display the header information for the second block of the bitmap index named
          <codeph>i1</codeph>:</p>
        <codeblock>testdb=# SELECT * FROM bm_bitmap_page_header('i1', 2);
 num_words | next_blkno | last_tid 
-----------+------------+----------
 3         | 4294967295 | 65536    
(1 row)</codeblock>
        <p>Display the LOV items located in the first block of the bitmap
          index named <codeph>i1</codeph>:</p>
        <codeblock>testdb=# SELECT * FROM bm_lov_page_items('i1', 1) ORDER BY itemoffset;
 itemoffset | lov_head_blkno | lov_tail_blkno | last_complete_word      | last_word               | last_tid | last_setbit_tid | is_last_complete_word_fill | is_last_word_fill 
------------+----------------+----------------+-------------------------+-------------------------+----------+-----------------+----------------------------+-------------------
 1          | 4294967295     | 4294967295     | ff ff ff ff ff ff ff ff | 00 00 00 00 00 00 00 00 | 0        | 0               | f                          | f                 
 2          | 2              | 2              | 80 00 00 00 00 00 00 01 | 00 00 00 00 07 ff ff ff | 65600    | 65627           | t                          | f                 
 3          | 3              | 3              | 80 00 00 00 00 00 00 02 | 00 3f ff ff ff ff ff ff | 131200   | 131254          | t                          | f                 
(3 rows)</codeblock>
        <p>Return the content words located in the second block of the bitmap index named
          <codeph>i1</codeph>:</p>
        <codeblock>testdb=# SELECT * FROM bm_bitmap_page_items('i1', 2) ORDER BY word_num;
 word_num | compressed | content_word            
----------+------------+-------------------------
 0        | t          | 80 00 00 00 00 00 00 0e 
 1        | f          | 00 00 00 00 00 00 1f ff 
 2        | t          | 00 00 00 00 00 00 03 f1 
(3 rows)</codeblock>
        <p>Alternatively, return the content words located in the heap page image of the
          same bitmap index and block:</p>
        <codeblock>testdb=# SELECT * FROM bm_bitmap_page_items(get_raw_page('i1', 2)) ORDER BY word_num;
 word_num | compressed | content_word            
----------+------------+-------------------------
 0        | t          | 80 00 00 00 00 00 00 0e 
 1        | f          | 00 00 00 00 00 00 1f ff 
 2        | t          | 00 00 00 00 00 00 03 f1 
(3 rows)</codeblock>
       </section>
     </body>
   </topic>
  </topic>
</dita>
